Draft ESP cheatsheet as of 3/21/07

This will likely need to be put into a Word document.
Feedback appreciated...

------------

Avoiding a position on a rotary valve example------>       PTV.to :puck, :avoiding=>:PRV  

Preparation for running high level protocols in the lab:

0) Insure that no one else has is running the esp
   application on the ESPhost machine

1)  ssh to the ESPhost machine as the appropriate user
        (most often this will be user esp or scholin)
$ ssh user@espHost

2)  confirm the ESP is getting the right code base
    check the Using ... line that appears right after the login
    It should say
      Using esp@espbook, ESPhome=/home/esp/esp2 for user scholin
        or
      Using esp2local, ESPhome=/home/esp/esp2 for user esp

    The message:

      WARNING:  ESPhome is undefined!

    indicates a transient network filesystem problem (NFS).
    If the machine is in a safe state, simply logout, cycle its
    power and try again after 30 seconds or so.  Alternatively,
    you can login as the root use and type:

# service nfsmount start

    After the nfsmounts all complete, logout of root and
    try logging in as scholin
    again.  You should not see this problem when logging in
    as user esp, as this user does not rely on NFS mounts.

3)  start the esp application

$ esp

4)  Insure that the ESP is homed and ready:

esp>  ESP.ready!

5)  Visually verify that the FlushPuck is in its garage.

Now, after loading the appropriate puck(s),
you will be ready to run your protocols as follows:

[Whole Cell Archive]
        wcr sampleVolume, bubblePt, fixTime=60*60, fixes=3, fixVolume=2

Example:
esp>    startTube 3     #pull WCR puck from tube 3, discard into tube 2
esp>    wcr  200, 24    #sample 200ml, filter bubblePoint of 24psi
#defaults to 3 (20 minute) fixes of 2ml each.

[Short Sandwich Hybridization phase 2 for in lab testing]
        shortSh2(signal=:sig1, hash={}, &wcrBlock)

Examples:
esp>    startTube 2     #pull pucks from tube 2, discard into tube 1
esp>    shortSh2 :sig2, :assay=>:bac  #run BAC assay using :sig2

esp>    shortSh2(:sig1, :assay=>:hab)

        #hab assay followed by wcr

[Harmful Algae Bloom]
        HAB(sampleVolume=400, wcrVol=50, &cleanup)   #with initialPurge
        hab(sampleVolume=400, wcrVol=50, &cleanup)   #w/o initialPurge

Examples:
        startTube 7     #pull 4 pucks from tube 7, discard into 6
esp>    HAB    #sample 400ml, wcr 50ml, standard killIntake cleanup
esp>    HAB 1200, 100         #1200ml sample, 100ml wcr
esp>    hab(1000)

  #1000ml sample
                #skip intialPurge, do not purge or kill Intake

[Bacterial]
        BAC(sampleVolume=100, wcrVol=50, &cleanup)   #with initialPurge
        bac(sampleVolume=100, &cleanup)   #without initialPurge

Examples:
esp>    startTube 5     #pull 4 pucks from tube 5, discard into 4
esp>    BAC    #sample 100ml, wcr 50ml, standard killIntake cleanup
esp>    HAB 1700, 800         #1700ml sample, 800ml wcr
esp>    bac(1500, 500)

  #1500ml sample, 500ml wcr
                #skip intialPurge, do not purge or kill Intake

[Demoic Acid]
        DA(sampleVolume=750, &cleanup)   #with initialPurge
        da(sampleVolume=750, &cleanup)   #without initialPurge

Examples:
esp>    startTube 6     #pull 3 pucks from tube 6, discard into 4
esp>    DA    #sample 100ml, NO WCR, standard killIntake cleanup
esp>    DA 1200                              #1200ml sample, no wcr
esp>    da(1250)

)}
                #1200ml sample, 500ml DA, (50ml wcr)
                #skip intialPurge, do not purge or kill Intake

==============
Image Capture

All the above protocols (except wcr) take additional (optional)
:key=>:value type parameters that can be used to alter the image
capture settings.  By default, three images are taken.

Image #1:  10 seconds with 4x4 binning
Image #2:  30 seconds with 4x4 binning
Image #3:  hi-resolution Auto exposure

The :image key can be used to override this for a
given protocol run as follows:

esp>    HAB 500, 50, :image=>[5, :hires, 40, :auto, :midres, 20]

This takes the following images:

Image #1:  5 seconds with default (4x4) binning
Image #2: 40 seconds with no binning (hi-resolution)
Image #3: hi-resolution Auto exposure
Image #4: 20 seoncds with 2x2 binning

See the Exposures, ImageMode and PuckCamera declarations in
shallow/configure.rb for more details on setting default
binning, image output directory, etc.

==============
Gigi's puck handling comands have undergone quite a bit of revision
over that past couple months.
Here's an updated command reference:

*Puck Handling commands*
[This is copied from a mail I originally sent the list on 1/18/07]

CC.loadPuck  label, fromTube=nil
PC.loadPuck  label, fromTube=nil
# load a puck from the specified carousel tube into
# the respective clamp (CC or PC).  Use the required
# puck label help to track it.  Typical labels are:
#  :sh1, :sh2, :lyfil, :WCR, etc.  The labels will soon enable
# the ESP to produce instructions for loading
# the carousel prior to a mission.  For now, they
# just show up as helpful comments in the log.
# If the fromTube is not specified, then the puck
# is taken from the currently defined "startTube"
# If that "startTube" is empty, it advances
# "startTube" to the next tube automatically.
# This lets puck sets span tubes if desired.

CC.unloadPuck  toTube=Storage.dstTube
PC.unloadPuck  toTube=Storage.dstTube
# unload puck in specified clamp to specified carousel tube.
# If toTube is not specified, the puck is stored
# in the "destination tube".  For now, the "destination tube"
# is simply one less than the current startTube.
# For this reason, is it not advisible to set startTube to 1.

startTube  tubeNumber=nil
# define the current start or sourceTube for loadPuck.
# if tubeNumber is omitted, the current startTube
# is returned, unchanged.

dstTube
# returns the current default destination tube for
# unloadPuck.  There is no way to set this explicitly.
# For now, it is defined as 1 less than startTube.

access  tubeNumber=SC.position.base
# Rotate the carousel such that the specified tube
# is accessible for manually loading and unloading pucks.
# if tubeNumber is omitted, the currently selected
# tube is made accessible.

CC.contains
PC.contains
# return the label of the puck currently clamped
# Handy if you've forgotten what's where...

Flush.to CC
Flush.to PC
CC.loadFlush
PC.loadFlush
# all these simply load the flush puck into the specified clamp

Flush.garage clampledPos=nil
# put the flush puck back into its garage
# The clamp need not normally be specified, as the system
# will track where the FlushPuck is currently clamped.
# It may be specifed to explicity override the system's
# record of the current FlushPucks position.

PC.unloadFlush
CC.unloadFlush
# equivalent to
#  Flush.garage PC  or   Flush.garage  CC

Puck.move  fromTube, toTube
# move the tube at the top of tube fromTube
# to the top of top toTube

Puck.count  tubes=1..SCtubes
# count the number of pucks in the specified tubes
# of tubes is omitted, count the # of pucks in all tubes.
# This works by measuring the height of each respective
# puck stack.

Storage.pucks
# returns a hash of tube numbers to their respecive
# puck stack heights.  The unit of measure such that
# 1.0 = one standard puck.  The results are fractional
# due to measurement errors and puck height variences.

Storage.pucks.sort.collect

# This incantation will return an array with each element
# corresponding to the number of pucks in that tube.

=================

Multithreading has introduced the concept of locking the Arm and the
FlushPuck to a particular thread to ensure that no other thread can
hijack those resources while that are in use.  The FlushPuck and Puck
load/unload commands handle this locking more or less transparently.
The Arm is locked for as long as it takes to complete the requested puck
move.  The FlushPuck is locked whenever it is not garaged.

If a script attempts to move a puck while the Arm is locked, you will
see the message:

Waiting for (threadName) to free Arm
==or==
Waiting for (threadName) to free FlushPuck

Normally, the thread will eventually free the resource, allowing the waiting
thread to continue after claiming it.  However,
The system can become confused if a puck movement is interrupted either
by an error or user abort.  In this case, the thread that locked the Arm
and/or FlushPuck may be dead and the system in an indeterminate state.
The commands:

Arm.reset
FlushPuck.reset

May be used to in this case to reset the locks so that new threads may
access the resources.  Normally, these command would be executed
only after the ESP was carefully inspected and returned to a safe state
using low level Arm.commands.  For instance, if a user aborted loading
a FlushPuck into CC, the reovery sequence might be:

CC.open
Arm.releaseAt  :garage
Arm.reset
FlushPuck.reset

Note that, if another thread is waiting on the resource, it will be able
to acquire it and continue after Arm/FlushPuck .reset.  Therefore,
it is important not to reset until the system is put back into
a "safe" state.  Also note that the primitive Arm.commands
do not respect the state of any locks, whereas the FlushPuck
and other higher-level puck movement commands do.
This rule allows users to interactively move the Arm to clear
errors without first resetting the locks.

And, a quicky new Arm command:

Arm.withdraw
#retract the arm without opening the hand.